Handling Network Errors, Timeouts, and HTTP Status Codes in iOS

Course: iOS App Development

Topic: Handling Network Errors, Timeouts, and HTTP Status Codes

Course Link: iOS App Development Training

Demo Link: Register for a Free Course Demo

Website: JustAcademy

1. Introduction to Network Error Handling in iOS

Modern iOS applications frequently communicate with remote servers to retrieve information, authenticate users, upload files, submit forms, and synchronize application data. These operations typically use HTTP or HTTPS requests through Swift's networking APIs, such as URLSession.

Network communication can fail for several reasons, including an unavailable internet connection, an unreachable server, a slow response, an invalid request, expired authentication credentials, or an unexpected server error. An iOS application must identify these situations and respond appropriately rather than crashing or leaving users waiting indefinitely.

Network error handling involves three important areas:

• Network errors: Problems that prevent a request from completing successfully, such as connection failures or DNS resolution errors.
• Timeouts: Situations in which a connection or request takes longer than the configured time limit.
• HTTP status codes: Numeric codes returned by a server to describe the outcome of an HTTP request.

2. Learning Objectives

After completing this topic, learners will be able to:

• Understand common networking problems in iOS applications.
• Use URLSession to detect and handle request failures.
• Configure connection and resource timeouts.
• Identify and interpret HTTP status codes.
• Handle unsuccessful HTTP responses using Swift error handling.
• Implement retry logic for temporary failures.
• Display meaningful error messages to users.
• Build reliable API communication using reusable networking functions.

3. Understanding URLSession Networking

URLSession is Apple's primary API for performing HTTP and HTTPS networking tasks. It supports data requests, file downloads, uploads, background transfers, and asynchronous networking operations.

A typical request follows these steps:

1. Create a URL representing the API endpoint.
2. Create a URLRequest and configure its properties.
3. Execute the request through URLSession.
4. Check whether a transport-level error occurred.
5. Validate the HTTP response and status code.
6. Decode the response data or report an appropriate error.

Example: A Basic Network Request

import Foundation

let url = URL(string: "https://jsonplaceholder.typicode.com/posts/1")!

URLSession.shared.dataTask(with: url) { data, response, error in
    if let error = error {
        print("Network error: \(error.localizedDescription)")
        return
    }

    guard let httpResponse = response as? HTTPURLResponse else {
        print("Invalid server response")
        return
    }

    guard (200...299).contains(httpResponse.statusCode) else {
        print("HTTP status code: \(httpResponse.statusCode)")
        return
    }

    guard let data = data else {
        print("No response data received")
        return
    }

    print("Request successful. Received \(data.count) bytes.")
}.resume()

Explanation: The completion handler receives response data, response metadata, and an optional transport error. The code checks the error first, verifies that the response is an HTTP response, validates its status code, and then processes the returned data.

Calling resume() starts the suspended data task. Without it, the request does not begin.

4. Common Network Errors in iOS

Network failures may occur before a request reaches the server, while the request is being processed, or while the response is being received.

5. Understanding URLError in Swift

Swift's URLError type represents many errors associated with URL loading and networking. Its error codes can help an application decide whether to retry, show a connection message, or stop processing.

Common URLError Codes

Example: Handling Specific Network Errors

import Foundation

func handleNetworkError(_ error: Error) {
    guard let urlError = error as? URLError else {
        print("Unexpected error: \(error.localizedDescription)")
        return
    }

    switch urlError.code {
    case .notConnectedToInternet:
        print("Please check your internet connection.")

    case .timedOut:
        print("The request timed out. Please try again.")

    case .cannotFindHost, .cannotConnectToHost:
        print("The server is currently unreachable.")

    case .networkConnectionLost:
        print("The network connection was interrupted.")

    case .cancelled:
        print("The request was cancelled.")

    default:
        print("Network error: \(urlError.localizedDescription)")
    }
}

Important: An error code identifies a possible failure category, but it does not always explain the complete underlying cause. For example, a timeout can result from a slow server, poor connectivity, or an unreachable endpoint.

6. Understanding HTTP Status Codes

HTTP status codes are returned by a server in the HTTP response. They describe whether the request succeeded, requires further action, or failed.

HTTP status codes are different from transport errors. A transport error may prevent an HTTP response from being received at all. An HTTP error status, such as 404 or 500, means the client received an HTTP response from the server.

6.1 Informational Responses: 1xx

These codes indicate that the request is still being processed or that additional protocol action is taking place. They are generally handled by the HTTP networking layer rather than ordinary application-level response logic.

6.2 Successful Responses: 2xx

6.3 Redirection Responses: 3xx

URLSession normally handles many redirects automatically. Developers should still understand redirect behavior when working with authentication, API gateways, and security-sensitive endpoints.

6.4 Client Error Responses: 4xx

6.5 Server Error Responses: 5xx

Some 5xx errors are temporary and may be retried. Others require server-side investigation. Retry decisions should depend on the request method, server guidance, and the possibility of duplicate operations.

7. Creating a Custom Network Error Type

In a larger iOS application, network errors should be represented consistently. A custom Swift error type allows the networking layer to communicate meaningful failures to the user interface.

import Foundation

enum NetworkError: Error {
    case invalidURL
    case noData
    case invalidResponse
    case httpStatus(Int)
    case decodingFailed
}

Each case represents a specific failure. The httpStatus(Int) case preserves the received status code so the application can handle individual responses when necessary.

8. Building a Reusable Network Request Function

A reusable networking function reduces duplicated code and ensures that every request checks transport errors, HTTP responses, and status codes consistently.

import Foundation

enum NetworkError: Error {
    case invalidResponse
    case httpStatus(Int)
    case noData
}

func fetchData(from url: URL) async throws -> Data {
    let (data, response) = try await URLSession.shared.data(from: url)

    guard let httpResponse = response as? HTTPURLResponse else {
        throw NetworkError.invalidResponse
    }

    guard (200...299).contains(httpResponse.statusCode) else {
        throw NetworkError.httpStatus(httpResponse.statusCode)
    }

    return data
}

How it works:

• async marks the function as asynchronous.
• throws allows the function to report networking or validation failures.
• URLSession.shared.data(from:) asynchronously returns response data and response metadata.
• The HTTP response check ensures that the returned response is valid.
• The status code check rejects unsuccessful HTTP responses.
• The function returns data only after successful HTTP validation.

The function propagates transport errors from URLSession. It does not automatically decode JSON; decoding can be performed by the caller.

9. Handling Network Errors with do-catch

Swift's do-catch statement handles errors thrown by asynchronous networking functions. It allows developers to distinguish expected HTTP failures from other networking errors.

func loadPost() async {
    guard let url = URL(
        string: "https://jsonplaceholder.typicode.com/posts/1"
    ) else {
        print("Invalid URL")
        return
    }

    do {
        let data = try await fetchData(from: url)
        print("Received \(data.count) bytes")

    } catch let NetworkError.httpStatus(code) {
        print("The server returned HTTP \(code)")

    } catch let urlError as URLError {
        switch urlError.code {
        case .notConnectedToInternet:
            print("Check your internet connection.")
        case .timedOut:
            print("The request took too long.")
        default:
            print("Network issue: \(urlError.localizedDescription)")
        }

    } catch {
        print("Unexpected error: \(error.localizedDescription)")
    }
}

For a production app, this function could update an observable view model property so that SwiftUI can display a loading indicator, the retrieved content, or an error message.

10. Understanding Request Timeouts

A timeout defines how long a networking operation is allowed to wait before it fails. Appropriate timeout settings prevent applications from waiting indefinitely and help provide a predictable user experience.

URLSession provides two important timeout settings through URLSessionConfiguration.

These settings have different purposes. A request timeout is not necessarily a strict deadline for the entire operation, because the request can continue while data arrives. The resource timeout places an upper bound on the overall transfer duration.

Example: Configuring Timeouts

import Foundation

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
configuration.timeoutIntervalForResource = 60

let session = URLSession(configuration: configuration)

func fetchExample() async {
    guard let url = URL(
        string: "https://jsonplaceholder.typicode.com/posts/1"
    ) else {
        print("Invalid URL")
        return
    }

    do {
        let (data, response) = try await session.data(from: url)

        guard let httpResponse = response as? HTTPURLResponse else {
            print("Invalid response")
            return
        }

        guard (200...299).contains(httpResponse.statusCode) else {
            print("HTTP error: \(httpResponse.statusCode)")
            return
        }

        print("Downloaded \(data.count) bytes")
    } catch {
        print("Request failed: \(error.localizedDescription)")
    }
}

Explanation: This configuration sets a 30-second request timeout and a 60-second resource timeout. These are example values, not universal recommendations. Choose values based on the API, expected payload size, network conditions, and user experience.

11. Handling HTTP Status Codes in Swift

URLSession does not automatically treat every non-2xx HTTP response as a thrown error. A response with status code 404 or 500 can still be returned successfully at the transport layer. Therefore, the application must inspect HTTPURLResponse.statusCode.

func validateResponse(_ response: URLResponse) throws {
    guard let httpResponse = response as? HTTPURLResponse else {
        throw NetworkError.invalidResponse
    }

    switch httpResponse.statusCode {
    case 200...299:
        print("Success")

    case 400...499:
        throw NetworkError.httpStatus(httpResponse.statusCode)

    case 500...599:
        throw NetworkError.httpStatus(httpResponse.statusCode)

    default:
        throw NetworkError.httpStatus(httpResponse.statusCode)
    }
}

This example separates successful responses from other status codes. A more advanced implementation can map specific status codes to user-friendly errors, authentication recovery, validation feedback, or retry decisions.

12. Displaying User-Friendly Error Messages

Technical error messages are useful during debugging but may confuse end users. Applications should translate technical failures into clear, actionable messages.

Do not expose sensitive server details, internal stack traces, access tokens, or private response information in user-facing error messages.

13. Implementing Retry Logic

Retry logic allows an application to repeat a request after a temporary failure. It is useful for certain connection interruptions, timeouts, and temporary server errors.

However, retries should be controlled. Repeated requests can overload a server, trigger rate limits, or create duplicate records if an operation is performed more than once.

Recommended Retry Rules

• Set a maximum number of attempts.
• Use exponential backoff to increase the delay between attempts.
• Add random jitter to reduce simultaneous retries from many clients.
• Respect the server's Retry-After header when appropriate.
• Retry only errors that are likely to be temporary.
• Be particularly careful with POST requests and other non-idempotent operations.
• Stop retrying when the user cancels the operation.

Example: Retry with Exponential Backoff

import Foundation

func fetchWithRetry(
    url: URL,
    maxAttempts: Int = 3
) async throws -> Data {
    let session = URLSession.shared

    for attempt in 1...maxAttempts {
        do {
            let (data, response) = try await session.data(from: url)

            guard let httpResponse = response as? HTTPURLResponse else {
                throw NetworkError.invalidResponse
            }

            guard (200...299).contains(httpResponse.statusCode) else {
                throw NetworkError.httpStatus(httpResponse.statusCode)
            }

            return data

        } catch {
            if Task.isCancelled {
                throw CancellationError()
            }

            guard attempt < maxAttempts,
                  isRetryable(error) else {
                throw error
            }

            let baseDelay = pow(2.0, Double(attempt - 1))
            let jitter = Double.random(in: 0...0.5)
            let delay = baseDelay + jitter

            try await Task.sleep(
                for: .seconds(delay)
            )
        }
    }

    throw NetworkError.noData
}

func isRetryable(_ error: Error) -> Bool {
    if let urlError = error as? URLError {
        switch urlError.code {
        case .timedOut,
             .networkConnectionLost,
             .cannotConnectToHost:
            return true
        default:
            return false
        }
    }

    if let networkError = error as? NetworkError,
       case let .httpStatus(code) = networkError {
        return [408, 429, 500, 502, 503, 504].contains(code)
    }

    return false
}

Important implementation notes:

• This example retries selected network errors and HTTP status codes, but production retry policies should be tailored to the API.
• The sample does not parse the Retry-After header; implement that behavior when required by the API contract.
• Use a dedicated session with sensible timeout configuration for production requests.
• Automatic retries should generally be limited to safe or idempotent operations, unless the server supports an idempotency key or another duplicate-prevention mechanism.
• For a production implementation, ensure all error types used in the sample are declared in the same module, including the NetworkError enum from the earlier section.

14. Handling Timeouts and Cancellation in Swift Concurrency

Swift concurrency makes asynchronous networking easier to read, but cancellation and timeouts still need deliberate handling. Cancelling a task requests that its work stop; it does not guarantee that every underlying operation immediately terminates.

URLSession supports task cancellation. A cancellation may be represented by CancellationError or a URLError.cancelled, depending on how the operation is cancelled and where the error is handled.

func loadData() async {
    guard let url = URL(
        string: "https://jsonplaceholder.typicode.com/posts/1"
    ) else {
        return
    }

    do {
        let data = try await fetchData(from: url)
        print("Loaded \(data.count) bytes")
    } catch is CancellationError {
        print("Task cancelled")
    } catch let error as URLError where error.code == .cancelled {
        print("Network request cancelled")
    } catch {
        print("Request failed: \(error.localizedDescription)")
    }
}

For strict end-to-end deadlines, design an explicit timeout policy that cancels the associated operation when the deadline expires. Avoid assuming that every networking timeout setting alone represents an exact wall-clock deadline for the entire application workflow.

15. Using Network Connectivity Monitoring

Apple provides NWPathMonitor through the Network framework to observe changes in the available network path.

Connectivity monitoring can help an application update its interface when connectivity changes. However, a reported available path does not guarantee that a particular API server is reachable, that DNS will resolve, or that a request will succeed.

import Foundation
import Network

let monitor = NWPathMonitor()
let monitorQueue = DispatchQueue(label: "NetworkMonitorQueue")

monitor.pathUpdateHandler = { path in
    if path.status == .satisfied {
        print("A network path is available")
    } else {
        print("No available network path")
    }
}

monitor.start(queue: monitorQueue)

// When monitoring is no longer needed:
// monitor.cancel()

In a SwiftUI application, connectivity status can be exposed through an observable model and used to show a non-blocking offline indicator. Actual API requests must still handle their own errors.

16. Logging and Debugging Network Errors

Logging helps developers identify the cause of failed requests and investigate intermittent problems.

Useful diagnostic information includes:

• API endpoint or a sanitized route name.
• HTTP method and response status code.
• Request duration and timeout information.
• Relevant URLError code.
• A request or correlation identifier, when provided by the server.
• A sanitized description of the failure.

Never log passwords, authorization headers, access tokens, session cookies, sensitive personal data, or complete confidential request bodies. Use controlled logging in production and consider Apple's unified logging facilities for structured diagnostics.

17. Common Mistakes to Avoid

18. Practical Project: Reliable API Data Loader

Build a small iOS application that retrieves a post from a public test API and displays the result or an appropriate error.

Project Requirements

• Create a SwiftUI screen with a Load Data button.
• Show a progress indicator while the request is running.
• Retrieve data using URLSession.
• Validate the HTTP response and status code.
• Decode the JSON response into a Swift model.
• Handle timeouts, connection failures, and HTTP errors.
• Provide a retry button for eligible failures.
• Display user-friendly messages instead of raw technical details.

Example Model and JSON Decoding

import Foundation

struct Post: Decodable {
    let userId: Int
    let id: Int
    let title: String
    let body: String
}

func fetchPost() async throws -> Post {
    guard let url = URL(
        string: "https://jsonplaceholder.typicode.com/posts/1"
    ) else {
        throw NetworkError.invalidResponse
    }

    let data = try await fetchData(from: url)

    do {
        return try JSONDecoder().decode(Post.self, from: data)
    } catch {
        throw NetworkError.decodingFailed
    }
}

This example builds on the reusable fetchData(from:) function and the custom NetworkError type defined earlier. In a complete application, the view model would manage loading, success, and failure states and expose them to the SwiftUI view.

19. Testing Network Error Handling

Network error handling should be tested deliberately rather than only under ideal conditions.

• Successful response: Verify that valid JSON is decoded correctly.
• HTTP 404: Confirm that the application displays a resource-not-found message.
• HTTP 401: Confirm that expired authentication is handled appropriately.
• HTTP 429: Verify that the retry policy respects server rate limits.
• HTTP 500: Confirm that temporary server failures are handled without crashing.
• Timeout: Test behavior when a response is delayed.
• Offline mode: Disable network access and verify the error state.
• Cancellation: Cancel an in-progress request and ensure the UI returns to an appropriate state.
• Empty response: Confirm that endpoints returning no content are handled correctly.

For automated tests, consider URLProtocol-based test doubles or a dedicated mock networking layer. This allows predictable HTTP responses and failures without relying on a live server.

20. Best Practices for Production iOS Applications

• Use HTTPS for API communication.
• Centralize request creation and HTTP response validation.
• Use typed models and Codable for JSON decoding.
• Configure appropriate request and resource timeouts.
• Distinguish transport failures from HTTP status errors.
• Apply bounded retries with exponential backoff and jitter when appropriate.
• Respect rate limits and server-provided retry instructions.
• Handle cancellation when views disappear or users stop an operation.
• Show clear error states and provide useful recovery actions.
• Keep UI updates on the appropriate actor, typically the main actor for UI state.
• Use structured logging without exposing confidential information.
• Test networking behavior under success, failure, timeout, and cancellation conditions.

21. Interview Questions and Answers

Q1. What is URLSession in iOS?

Answer: URLSession is Apple's networking API for sending HTTP and HTTPS requests, downloading files, uploading data, and performing background transfers.

Q2. What is the difference between a network error and an HTTP error?

Answer: A network error can prevent a request from completing or a response from being received. An HTTP error is a response received from a server with a status code indicating failure, such as 404 or 500.

Q3. What is a timeout?

Answer: A timeout limits how long a networking operation can wait or continue. It helps prevent requests from consuming time indefinitely when a connection or response is slow.

Q4. What is the difference between request and resource timeouts?

Answer: The request timeout controls waiting for additional data during a request, while the resource timeout limits the overall duration of the resource transfer.

Q5. Does URLSession throw an error for HTTP 404?

Answer: Not automatically for a normal data request. URLSession can return response data and an HTTP response with status code 404. The application must inspect the status code and handle it.

Q6. What does HTTP 401 mean?

Answer: It indicates that valid authentication credentials are missing or invalid. The application may need to refresh credentials or ask the user to sign in again.

Q7. What is the difference between HTTP 401 and 403?

Answer: HTTP 401 relates to authentication, whereas HTTP 403 indicates that the server refuses the requested action. The exact behavior depends on the API's authentication and authorization design.

Q8. When should an iOS application retry a request?

Answer: It should retry selected transient failures, such as certain connection interruptions, timeouts, or temporary server errors, while respecting retry limits and server instructions.

Q9. What is exponential backoff?

Answer: Exponential backoff progressively increases the delay between retry attempts. Jitter adds randomness to reduce the chance that many clients retry simultaneously.

Q10. What is NWPathMonitor?

Answer: NWPathMonitor is part of Apple's Network framework and observes changes in the available network path. It helps indicate connectivity state but cannot guarantee that a specific server request will succeed.

Q11. How should an application handle HTTP 429?

Answer: It should reduce request frequency, respect the Retry-After header when available, and avoid immediate repeated requests that may extend the rate limit.

Q12. Why is cancellation important in asynchronous networking?

Answer: Cancellation prevents unnecessary work when a user leaves a screen or no longer needs a result. It also helps manage resources and avoid displaying outdated results.

22. Practice Exercises

1. Create a URLSession request that handles HTTP 200 and HTTP 404 separately.
2. Configure a custom URLSession with request and resource timeouts.
3. Write a function that converts common URLError values into user-friendly messages.
4. Implement a retry policy with a maximum of three attempts.
5. Handle HTTP 401 by presenting a sign-in recovery action.
6. Simulate a 500 server response and test the application's error state.
7. Build a SwiftUI screen that displays loading, success, empty, and error states.
8. Write unit tests using a mocked URLSession response.

23. Quick Revision

• URLSession: Performs network requests and data transfers.
• URLError: Represents URL loading and transport-related errors.
• HTTP 2xx: Generally indicates a successful request.
• HTTP 4xx: Generally indicates a client-side request or authorization problem.
• HTTP 5xx: Generally indicates a server-side failure.
• Request timeout: Limits waiting for additional data during a request.
• Resource timeout: Limits the overall resource transfer duration.
• Retry logic: Repeats eligible operations under controlled conditions.
• NWPathMonitor: Observes network path availability.
• do-catch: Handles errors thrown by asynchronous networking operations.

24. Conclusion

Handling network errors, timeouts, and HTTP status codes is an essential skill for building dependable iOS applications. By using URLSession correctly, checking transport errors, validating HTTP responses, configuring suitable timeouts, and implementing controlled retry policies, developers can create applications that respond gracefully to unreliable networks and server failures.

A production-ready networking layer should combine clear error handling, secure communication, appropriate cancellation, structured diagnostics, and user-friendly recovery options. These practices help improve application stability and create a better experience for users.

Learn iOS App Development with JustAcademy

Explore iOS development training to strengthen your Swift, SwiftUI, networking, and API integration skills.

Course Page: Explore iOS App Development Training

Book a Demo: Register for a Course Demo

Visit JustAcademy: www.justacademy.co